(Quick Reference)
ui:field
Purpose
This tag renders an HTML form field, according to the type and constraint info of the field/property. The rendering includes all UI elements relating to the field, for example the label, any field errors, required indicators and field hints.
UI Sets and Themes can customise the rendering of the field to suit their HTML/CSS requirements, and the rendering can use any mechanism it likes i.e. grails-fields plugin or an inline implementation.
The various elements of a field can be overridden for situations where a GSP needs to supply customized markup but still operate within he structural markup provided by the UI Set. For example you may want to render a field that has a single label but contains to or more input controls. Use the nested tags
fieldLabel,
fieldInput,
fieldErrors and
fieldHint to achieve this.
There are at least two field rendering plugins for Grails - Bean Fields and the newer and better Fields plugin. In future there may be more options. A UI Set does not need to use any of them either, and can hand code the handling of fields.As a result, the i18n message resolution for field labels and hints must be handled by Platform UI so that plugins can supply label i18n messages
using a standard naming convention.
Example
<ui:field bean="${form}" name="name"/>
<ui:field bean="${contact}" name="address.cityOrState"/>
<ui:field name="field1" type="text" hint="This is a little hint" label="Text field"/>
Attributes
| Name | Required? | Description |
|---|
| name | yes | The name of the field or property to use. If a property the bean instance must be supplied, and the name can be a property path |
| type | | The type of field to render. See below for list of types that are (and must be) supported by a UI Set. If not specified, the UI Set must attempt to detect an appropriate type of field to use based on the available information - i.e. bean property type and/or value type. If this is specified, the UI Set must render the type requested, even if it differs from the type of the property (i.e. allows rendering number fields as text) |
| bean | | The bean to use when resolving the property specified in "name". Used to render fields for values represented by a property of an object in the current page |
| id | | An implicit "id" attribute is given the same value as the name unless you explicitly specify one. |
| hint | | A hint to be displayed to the user, to explaining the field. If not specified, the hint will be resolved as per the rules below |
| hintArgs | | Arguments to be used when building the i18n string for the hint |
| invalid | | Set to boolean true to indicate that the field value is not valid. Used if you need to override the normal mechanisms for detecting field errors. |
| required | | Set to boolean true to indicate that a value is or isn't required for this field. Use only if you need to override the normal mechanism that detects this if it is a field for a bean property |
| value | | Use to provide an explicit value for the field, if it must be different from the value of a bean property or if you are not using bean properties |
| label | | Specify the text or i18n message code to use as the label text. If not specified, the label will be resolved as per the rules below |
| labelArgs | | Arguments used to build the i18n message label |
Supported field types
When rendering fields for bean properties where type information is available, the UI Set must support
editing of any property type, using the best input style for the type - with a fallback to input type="text" for types that do not have a specific rendering in the UI Set.
In this scenario the field type is not needed unless you wish to override the default behaviour
The following types must be supported by the UI Set for overriding the field type used for a bean property, or to set the field type for non-bean inputs.
- text
- checkbox
- radio
- textarea
- datepicker
- select
Any unrecognized types must be passed through to
<input> and its
type attribute, so that standard HTML5 element type attributes are honoured.
Localization of labels
If specifying a bean, the label defaults to:
- i18n message retrieved using <bean's Class>.<name>.label
- i18n message retrieved using <name>.label
- the value of the
name attributed converted to "This Is My Field" natural language format
If not using a bean:
- i18n message retrieved using field.<name>.label
- i18n message retrieved using <name>.label
- the value of the
name attributed converted to "This Is My Field" natural language format
Localization of hints
This is done the same as labels, but with ".hint" instead of ".label" at the end of the keys